/*
 * KeyValueCoding.java
 *
 * Created on November 4, 2006, 8:51 PM
 *
 * To change this template, choose Tools | Template Manager
 * and open the template in the editor.
 */

package edu.umn.cs5115.scheduler.framework;

/**
 * Perhaps needless to say, this is very much inspired by Cocoa's KVC system.
 * @author grant
 */
public interface KeyValueCoding
{
    /**
     * Add a listener for a given key.  If the listener already is receiving
     * notifications for the given key, calling this method has no effect. (the
     * listener will not be added twice)
     * @param listener The object to notify when the value of the key changes.
     * @param key The key to observe for changes.
     */
    public void addListener(KeyValueObserver listener, String key);
    
    /**
     * Remove a listener from a given key.  If the listener isn't listening to
     * the given key, calling this method does nothing.  Calling this method 
     * does not affect other keys the listener may be listening to, to remove a 
     * listener from all keys, call removeListener(KeyValueObserver).
     * @param listener The listener to remove from the list of objects to 
     * receive notifications when the value of the key changes.
     * @param key The key this listener no longer wants to observe for changes.
     * @see #removeListener(KeyValueObserver)
     */
    public void removeListener(KeyValueObserver listener, String key);
    
    /**
     * Remove a listener so that it no longer receives notifications from this object.
     * If the specified listener isn't already listening to this object, this 
     * method has no effect.
     * @param listener The listener to remove.
     * @see #removeListener(KeyValueObserver, String)
     */
    public void removeListener(KeyValueObserver listener);
    
    /**
     * Get the value for a key.
     * @param key The key to get the value of.
     * @return An object containing the value of the key.
     */
    public Object getValueForKey(String key);
    
    /**
     * Set the value for a key.
     * @param key The key to set the value of.
     * @param value The new value for the key.
     */
    public void setValueForKey(String key, Object value);
}
